---
title: Watch and WatchOptions
sort: 14
contributors:
  - sokra
  - skipjack
  - SpaceK33z
  - EugeneHlushko
  - byzyk
  - spicalous
  - Neob91
  - Loonride
  - snitin315
  - chenxsan
---

Webpack can watch files and recompile whenever they change. This page explains how to enable this and a couple of tweaks you can make if watching does not work properly for you.

## watch

`boolean = false`

Turn on watch mode. This means that after the initial build, webpack will continue to watch for changes in any of the resolved files.

**webpack.config.js**

```javascript
module.exports = {
  //...
  watch: true,
};
```

T> In [webpack-dev-server](https://github.com/webpack/webpack-dev-server) and [webpack-dev-middleware](https://github.com/webpack/webpack-dev-middleware) watch mode is enabled by default.

## watchOptions

`object`

A set of options used to customize watch mode:

**webpack.config.js**

```javascript
module.exports = {
  //...
  watchOptions: {
    aggregateTimeout: 200,
    poll: 1000,
  },
};
```

### watchOptions.aggregateTimeout

`number = 20`

Add a delay before rebuilding once the first file changed. This allows webpack to aggregate any other changes made during this time period into one rebuild. Pass a value in milliseconds:

```javascript
module.exports = {
  //...
  watchOptions: {
    aggregateTimeout: 600,
  },
};
```

### watchOptions.ignored

`RegExp` `string` `[string]`

For some systems, watching many files can result in a lot of CPU or memory usage. It is possible to exclude a huge folder like `node_modules` using a regular expression:

**webpack.config.js**

```javascript
module.exports = {
  //...
  watchOptions: {
    ignored: /node_modules/,
  },
};
```

Alternatively, a glob pattern may be used:

**webpack.config.js**

```javascript
module.exports = {
  //...
  watchOptions: {
    ignored: '**/node_modules',
  },
};
```

It is also possible to use multiple glob patterns:

**webpack.config.js**

```javascript
module.exports = {
  //...
  watchOptions: {
    ignored: ['**/files/**/*.js', '**/node_modules'],
  },
};
```

In addition, you can specify an absolute path:

```js
const path = require('path');
module.exports = {
  //...
  watchOptions: {
    ignored: [path.posix.resolve(__dirname, './ignored-dir')],
  },
};
```

When using glob patterns, we convert them to regular expressions with [`glob-to-regexp`](https://github.com/fitzgen/glob-to-regexp), so make sure to get yourself familiar with it before you use glob patterns for `watchOptions.ignored`.

T> If you use `require.context`, webpack will watch your entire directory. You will need to ignore files and/or directories so that unwanted changes will not trigger a rebuild.

### watchOptions.poll

`boolean = false` `number`

Turn on [polling](<https://en.wikipedia.org/wiki/Polling_(computer_science)>) by passing `true` which would set the default poll interval to [`5007`](https://github.com/webpack/watchpack/blob/a54bcdb95759558ca5a9fc2819c4d71b771c162f/lib/DirectoryWatcher.js#L79), or specifying a poll interval in milliseconds:

**webpack.config.js**

```javascript
module.exports = {
  //...
  watchOptions: {
    poll: 1000, // Check for changes every second
  },
};
```

T> If watching does not work for you, try out this option. This may help issues with NFS and machines in VirtualBox, WSL, Containers, or Docker. In those cases, use a polling interval and ignore large folders like `/node_modules/` to keep CPU usage minimal.

### watchOptions.followSymlinks

Follow symbolic links while looking for a file. This is usually not needed as webpack already resolves symlinks with [`resolve.symlinks`](/configuration/resolve/#resolvesymlinks).

- Type: `boolean`
- Example:

  ```js
  module.exports = {
    //...
    watchOptions: {
      followSymlinks: true,
    },
  };
  ```

### watchOptions.stdin

Stop watching when stdin stream has ended.

- Type: `boolean`
- Example:

  ```js
  module.exports = {
    //...
    watchOptions: {
      stdin: true,
    },
  };
  ```

## Troubleshooting

If you are experiencing any issues, please see the following notes. There are a variety of reasons why webpack might miss a file change.

### Changes Seen But Not Processed

Verify that webpack is not being notified of changes by running webpack with the --progress flag. If progress shows on save but no files are outputted, it is likely a configuration issue, not a file watching issue.

```bash
webpack --watch --progress
```

### Not Enough Watchers

Verify that you have enough available watchers in your system. If this value is too low, the file watcher in Webpack won't recognize the changes:

```bash
cat /proc/sys/fs/inotify/max_user_watches
```

Arch users, add `fs.inotify.max_user_watches=524288` to `/etc/sysctl.d/99-sysctl.conf` and then execute `sysctl --system`. Ubuntu users (and possibly others), execute: `echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p`.

### macOS fsevents Bug

On macOS, folders can get corrupted in certain scenarios. See [this article](https://github.com/livereload/livereload-site/blob/master/livereload.com/_articles/troubleshooting/os-x-fsevents-bug-may-prevent-monitoring-of-certain-folders.md).

### Windows Paths

Because webpack expects absolute paths for many configuration options such as `__dirname + '/app/folder'` the Windows `\` path separator can break some functionality.

Use the correct separators. I.e. `path.resolve(__dirname, 'app/folder')` or `path.join(__dirname, 'app', 'folder')`.

### Vim

On some machines Vim is preconfigured with the [backupcopy option](http://vimdoc.sourceforge.net/htmldoc/options.html#'backupcopy') set to `auto`. This could potentially cause problems with the system's file watching mechanism. Switching this option to `yes` will make sure a copy of the file is made and the original one overwritten on save.

`:set backupcopy=yes`

### Saving in WebStorm

When using the JetBrains WebStorm IDE, you may find that saving changed files does not trigger the watcher as you might expect. Try disabling the `Back up files before saving` option in the settings, which determines whether files are saved to a temporary location first before the originals are overwritten: uncheck `File > {Settings|Preferences} > Appearance & Behavior > System Settings > Back up files before saving`. On some versions of Webstorm, this option may be called `Use "safe write" (save changes to a temporary file first)`.
